<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN"
   "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd">
<html>
<meta http-equiv="Content-Type" content="text/html; charset=UTF-8"/>
<head>
    <title>Reference</title>
    <link rel="stylesheet" href="../ldoc.css" type="text/css" />
</head>
<body>

<div id="container">

<div id="product">
	<div id="product_logo"></div>
	<div id="product_name"><big><b></b></big></div>
	<div id="product_description"></div>
</div> <!-- id="product" -->


<div id="main">


<!-- Menu -->

<div id="navigation">
<br/>
<h1>Duplex</h1>

<ul>
  <li><a href="../index.html">Index</a></li>
</ul>

<h2>Contents</h2>
<ul>
<li><a href="#Functions">Functions</a></li>
<li><a href="#Fields">Fields</a></li>
</ul>


<h2>Modules</h2>
<ul class="$(kind=='Topics' and '' or 'nowrap'">
  <li><a href="../modules/Duplex.Application.html">Duplex.Application</a></li>
  <li><a href="../modules/Duplex.Applications.Effect.html">Duplex.Applications.Effect</a></li>
  <li><a href="../modules/Duplex.Applications.GridPie.html">Duplex.Applications.GridPie</a></li>
  <li><a href="../modules/Duplex.Applications.Hydra.html">Duplex.Applications.Hydra</a></li>
  <li><a href="../modules/Duplex.Applications.Instrument.html">Duplex.Applications.Instrument</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.GridLayout.html">Duplex.Applications.Keyboard.GridLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.HarmonicLayout.html">Duplex.Applications.Keyboard.Layouts.HarmonicLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.IsomorphicLayout.html">Duplex.Applications.Keyboard.Layouts.IsomorphicLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.Layouts.PianoLayout.html">Duplex.Applications.Keyboard.Layouts.PianoLayout</a></li>
  <li><a href="../modules/Duplex.Applications.Keyboard.html">Duplex.Applications.Keyboard</a></li>
  <li><a href="../modules/Duplex.Applications.Matrix.html">Duplex.Applications.Matrix</a></li>
  <li><a href="../modules/Duplex.Applications.Metronome.html">Duplex.Applications.Metronome</a></li>
  <li><a href="../modules/Duplex.Applications.MidiActions.Bindings.html">Duplex.Applications.MidiActions.Bindings</a></li>
  <li><a href="../modules/Duplex.Applications.MidiActions.html">Duplex.Applications.MidiActions</a></li>
  <li><a href="../modules/Duplex.Applications.Mixer.html">Duplex.Applications.Mixer</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_group.html">Duplex.Applications.Mlrx.Mlrx_group</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_note.html">Duplex.Applications.Mlrx.Mlrx_note</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_pos.html">Duplex.Applications.Mlrx.Mlrx_pos</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.Mlrx_track.html">Duplex.Applications.Mlrx.Mlrx_track</a></li>
  <li><a href="../modules/Duplex.Applications.Mlrx.html">Duplex.Applications.Mlrx</a></li>
  <li><a href="../modules/Duplex.Applications.Navigator.html">Duplex.Applications.Navigator</a></li>
  <li><a href="../modules/Duplex.Applications.NotesOnWheels.html">Duplex.Applications.NotesOnWheels</a></li>
  <li><a href="../modules/Duplex.Applications.PatternCursor.html">Duplex.Applications.PatternCursor</a></li>
  <li><a href="../modules/Duplex.Applications.PatternSequence.html">Duplex.Applications.PatternSequence</a></li>
  <li><a href="../modules/Duplex.Applications.Recorder.html">Duplex.Applications.Recorder</a></li>
  <li><a href="../modules/Duplex.Applications.Repeater.html">Duplex.Applications.Repeater</a></li>
  <li><a href="../modules/Duplex.Applications.Rotate.html">Duplex.Applications.Rotate</a></li>
  <li><a href="../modules/Duplex.Applications.StepSequencer.html">Duplex.Applications.StepSequencer</a></li>
  <li><a href="../modules/Duplex.Applications.SwitchConfiguration.html">Duplex.Applications.SwitchConfiguration</a></li>
  <li><a href="../modules/Duplex.Applications.TestPad.html">Duplex.Applications.TestPad</a></li>
  <li><a href="../modules/Duplex.Applications.TrackSelector.html">Duplex.Applications.TrackSelector</a></li>
  <li><a href="../modules/Duplex.Applications.Transport.html">Duplex.Applications.Transport</a></li>
  <li><a href="../modules/Duplex.Applications.UIButtonTest.html">Duplex.Applications.UIButtonTest</a></li>
  <li><a href="../modules/Duplex.Applications.XYPad.html">Duplex.Applications.XYPad</a></li>
  <li><strong>Duplex.Automation</strong></li>
  <li><a href="../modules/Duplex.Browser.html">Duplex.Browser</a></li>
  <li><a href="../modules/Duplex.BrowserProcess.html">Duplex.BrowserProcess</a></li>
  <li><a href="../modules/Duplex.Canvas.html">Duplex.Canvas</a></li>
  <li><a href="../modules/Duplex.CanvasPoint.html">Duplex.CanvasPoint</a></li>
  <li><a href="../modules/Duplex.ControlMap.html">Duplex.ControlMap</a></li>
  <li><a href="../modules/Duplex.Device.html">Duplex.Device</a></li>
  <li><a href="../modules/Duplex.Display.html">Duplex.Display</a></li>
  <li><a href="../modules/Duplex.Globals.html">Duplex.Globals</a></li>
  <li><a href="../modules/Duplex.Message.html">Duplex.Message</a></li>
  <li><a href="../modules/Duplex.MessageStream.html">Duplex.MessageStream</a></li>
  <li><a href="../modules/Duplex.MidiDevice.html">Duplex.MidiDevice</a></li>
  <li><a href="../modules/Duplex.OscClient.html">Duplex.OscClient</a></li>
  <li><a href="../modules/Duplex.OscDevice.html">Duplex.OscDevice</a></li>
  <li><a href="../modules/Duplex.OscVoiceMgr.html">Duplex.OscVoiceMgr</a></li>
  <li><a href="../modules/Duplex.Preferences.html">Duplex.Preferences</a></li>
  <li><a href="../modules/Duplex.ProcessSlicer.html">Duplex.ProcessSlicer</a></li>
  <li><a href="../modules/Duplex.RoamingDSP.html">Duplex.RoamingDSP</a></li>
  <li><a href="../modules/Duplex.Scheduler.html">Duplex.Scheduler</a></li>
  <li><a href="../modules/Duplex.StateController.html">Duplex.StateController</a></li>
  <li><a href="../modules/Duplex.UIButton.html">Duplex.UIButton</a></li>
  <li><a href="../modules/Duplex.UIButtonStrip.html">Duplex.UIButtonStrip</a></li>
  <li><a href="../modules/Duplex.UIComponent.html">Duplex.UIComponent</a></li>
  <li><a href="../modules/Duplex.UIKey.html">Duplex.UIKey</a></li>
  <li><a href="../modules/Duplex.UIKeyPressure.html">Duplex.UIKeyPressure</a></li>
  <li><a href="../modules/Duplex.UILabel.html">Duplex.UILabel</a></li>
  <li><a href="../modules/Duplex.UIPad.html">Duplex.UIPad</a></li>
  <li><a href="../modules/Duplex.UIPitchBend.html">Duplex.UIPitchBend</a></li>
  <li><a href="../modules/Duplex.UISlider.html">Duplex.UISlider</a></li>
  <li><a href="../modules/Duplex.UISpinner.html">Duplex.UISpinner</a></li>
  <li><a href="../modules/Duplex.WidgetHooks.html">Duplex.WidgetHooks</a></li>
  <li><a href="../modules/Duplex.WidgetKeyboard.html">Duplex.WidgetKeyboard</a></li>
  <li><a href="../modules/Duplex.html">Duplex</a></li>
  <li><a href="../modules/main.html">main</a></li>
</ul>

</div>

<div id="content">

<h1>Module <code>Duplex.Automation</code></h1>
<p>Provide generic automation features for Duplex applications</p>

<p>In the Renoise API, each pattern-track can contain a list of automation envelopes which are listed in order-of-arrival.</p>
<p> This means that it's quite complicated to do something as simple as saying "write a point here for this parameter", because first you have to find the right envelope, or create it.</p>

<p>This class provides a much simpler way of writing automation, exposing just a single method, add_automation(). Provided with a track number, a parameter and a value, the rest happens automatically. If the continuous/latch recording mode is enabled, one also need to call the update() method with regular intervals to ensure that the envelope is being written ahead of the actual playback position. </p>

<p>To set up the Automation class, you need to instantiate it in your application (the <code>__init()</code> method), and make sure that <code>attach<em>to</em>song()</code> is called when the application is initialized, and new songs are created. </p>


<h2><a href="#Functions">Functions</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#__init">__init ()</a></td>
	<td class="summary">Initialize the Automation class</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#_get_extrapolation_strength">_get_extrapolation_strength ()</a></td>
	<td class="summary">Retrieve the extrapolation strength from Duplex setting</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#update">update ()</a></td>
	<td class="summary">Update currently recording automation lanes
 (this method is designed to be called from within an idle loop)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#add_automation">add_automation (track_idx, parameter, value, playmode)</a></td>
	<td class="summary">Add a point at current time (will add new automations on the fly)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_current_line">get_current_line ()</a></td>
	<td class="summary">Retrieve the current line</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_current_seq_index">get_current_seq_index ()</a></td>
	<td class="summary">Retrieve the current sequence index</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#add_point">add_point (ptrack_auto, line, value, automation_lane, playmode)</a></td>
	<td class="summary">This method is an enhanced version of add<em>point</em>at(), as it will wrap at
  pattern boundaries and create automation on the fly</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#writeahead">writeahead (amount, ptrack_auto, lane)</a></td>
	<td class="summary">"Write-ahead" using extrapolated values
 (enabled when dealing with cubic/linear envelopes)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#find_or_create">find_or_create (ptrack, autolane, seq_idx, register)</a></td>
	<td class="summary">Find<em>or</em>create will always return a PatternTrackAutomation index when
 provided with a valid PatternTrack.</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_automation_index">get_automation_index (ptrack, ptrack_auto)</a></td>
	<td class="summary">Figure out the track automation's index</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#get_device_by_param">get_device_by_param (track_idx, parameter)</a></td>
	<td class="summary">Figure out the device by supplying a parameter</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#stop_automation">stop_automation ()</a></td>
	<td class="summary">Stop all currently recording automation</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#attach_to_song">attach_to_song (new_song)</a></td>
	<td class="summary">Attach to song (call this from the host application)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#_remove_notifiers">_remove_notifiers (new_song)</a></td>
	<td class="summary">Remove all notifiers associated with this class instance</td>
	</tr>
</table>
<h2><a href="#Fields">Fields</a></h2>
<table class="function_list">
	<tr>
	<td class="name" nowrap><a href="#self.latch_record">self.latch_record</a></td>
	<td class="summary">(bool) set this to true when data is continuously output</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.stop_at_loop">self.stop_at_loop</a></td>
	<td class="summary">(bool) if true, recording will not cross pattern boundaries</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.preferred_playmode">self.preferred_playmode</a></td>
	<td class="summary">(enum) leave undefined, or set to
 renoise.PatternTrackAutomation.PLAYMODE<em>POINTS
 renoise.PatternTrackAutomation.PLAYMODE</em>LINEAR
 renoise.PatternTrackAutomation.PLAYMODE_CUBIC</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.follow_pos">self.follow_pos</a></td>
	<td class="summary">(enum) how position is determined</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.extrapolate_strength">self.extrapolate_strength</a></td>
	<td class="summary">extrapolation strength, 3 is the default value
 range is from 1 and up, with higher values causing more overshooting
 (when recording, choose point envelopes to avoid extrapolation at all)</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self._automations">self._automations</a></td>
	<td class="summary">AutomationLane instances</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self._skip_updates">self._skip_updates</a></td>
	<td class="summary">temporarily skip output while recording slider movements</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.map">self.map</a></td>
	<td class="summary">list of active observables</td>
	</tr>
	<tr>
	<td class="name" nowrap><a href="#self.parameter">self.parameter</a></td>
	<td class="summary">automation indices are kept here</td>
	</tr>
</table>

<br/>
<br/>


    <h2><a name="Functions"></a>Functions</h2>
    <dl class="function">
    <dt>
    <a name = "__init"></a>
    <strong>__init ()</strong>
    </dt>
    <dd>
    Initialize the Automation class







</dd>
    <dt>
    <a name = "_get_extrapolation_strength"></a>
    <strong>_get_extrapolation_strength ()</strong>
    </dt>
    <dd>
    Retrieve the extrapolation strength from Duplex setting







</dd>
    <dt>
    <a name = "update"></a>
    <strong>update ()</strong>
    </dt>
    <dd>
    Update currently recording automation lanes
 (this method is designed to be called from within an idle loop)







</dd>
    <dt>
    <a name = "add_automation"></a>
    <strong>add_automation (track_idx, parameter, value, playmode)</strong>
    </dt>
    <dd>
    Add a point at current time (will add new automations on the fly)


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">track_idx</span>
         (int) the track index
        </li>
        <li><span class="parameter">parameter</span>
         (DeviceParameter object)
        </li>
        <li><span class="parameter">value</span>
         (number between 0-1)
        </li>
        <li><span class="parameter">playmode</span>
         (enum), renoise.PatternTrackAutomation.PLAYMODE_xxx
        </li>
    </ul>





</dd>
    <dt>
    <a name = "get_current_line"></a>
    <strong>get_current_line ()</strong>
    </dt>
    <dd>
    Retrieve the current line



    <h3>Returns:</h3>
    <ol>

        int
    </ol>




</dd>
    <dt>
    <a name = "get_current_seq_index"></a>
    <strong>get_current_seq_index ()</strong>
    </dt>
    <dd>
    Retrieve the current sequence index



    <h3>Returns:</h3>
    <ol>

        int
    </ol>




</dd>
    <dt>
    <a name = "add_point"></a>
    <strong>add_point (ptrack_auto, line, value, automation_lane, playmode)</strong>
    </dt>
    <dd>
    This method is an enhanced version of add<em>point</em>at(), as it will wrap at
  pattern boundaries and create automation on the fly


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">ptrack_auto</span>
         (PatternTrackAutomation)
        </li>
        <li><span class="parameter">line</span>
         (int), line in pattern
        </li>
        <li><span class="parameter">value</span>
         (number), between 0 and 1
        </li>
        <li><span class="parameter">automation_lane</span>
         (AutomationLane), when called from update()
        </li>
        <li><span class="parameter">playmode</span>
         (enum), [optional] renoise.PatternTrackAutomation.PLAYMODE_xxx
        </li>
    </ul>





</dd>
    <dt>
    <a name = "writeahead"></a>
    <strong>writeahead (amount, ptrack_auto, lane)</strong>
    </dt>
    <dd>
    "Write-ahead" using extrapolated values
 (enabled when dealing with cubic/linear envelopes)


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">amount</span>
         (int), number of extrapolated points, 0 and up
        </li>
        <li><span class="parameter">ptrack_auto</span>
         (renoise.PatternTrackAutomation)
        </li>
        <li><span class="parameter">lane</span>
         (AutomationLane)
        </li>
    </ul>





</dd>
    <dt>
    <a name = "find_or_create"></a>
    <strong>find_or_create (ptrack, autolane, seq_idx, register)</strong>
    </dt>
    <dd>
    Find<em>or</em>create will always return a PatternTrackAutomation index when
 provided with a valid PatternTrack.  The PatternTrackAutomation object is
 created on-the-fly if not already present
 note: when playback progress into pattern that does not (yet) contain
 any automation, supply a negative value ("waiting for observable")


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">ptrack</span>
         (PatternTrack)
        </li>
        <li><span class="parameter">autolane</span>
         (AutomationLane)
        </li>
        <li><span class="parameter">seq_idx</span>
         (int) the sequence index
        </li>
        <li><span class="parameter">register</span>
         (bool) register as "waiting for observable"
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        (int), the resulting index
    </ol>




</dd>
    <dt>
    <a name = "get_automation_index"></a>
    <strong>get_automation_index (ptrack, ptrack_auto)</strong>
    </dt>
    <dd>
    Figure out the track automation's index


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">ptrack</span>
         (PatternTrack)
        </li>
        <li><span class="parameter">ptrack_auto</span>
         (PatternTrackAutomation)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        (int) the automation index
    </ol>




</dd>
    <dt>
    <a name = "get_device_by_param"></a>
    <strong>get_device_by_param (track_idx, parameter)</strong>
    </dt>
    <dd>
    Figure out the device by supplying a parameter


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">track_idx</span>
         (int)
        </li>
        <li><span class="parameter">parameter</span>
         (DeviceParameter)
        </li>
    </ul>

    <h3>Returns:</h3>
    <ol>

        TrackDevice
    </ol>




</dd>
    <dt>
    <a name = "stop_automation"></a>
    <strong>stop_automation ()</strong>
    </dt>
    <dd>
    Stop all currently recording automation







</dd>
    <dt>
    <a name = "attach_to_song"></a>
    <strong>attach_to_song (new_song)</strong>
    </dt>
    <dd>
    Attach to song (call this from the host application)


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">new_song</span>



        </li>
    </ul>





</dd>
    <dt>
    <a name = "_remove_notifiers"></a>
    <strong>_remove_notifiers (new_song)</strong>
    </dt>
    <dd>
    Remove all notifiers associated with this class instance


    <h3>Parameters:</h3>
    <ul>
        <li><span class="parameter">new_song</span>
         (bool) if defined, do not attempt to remove notifiers
        </li>
    </ul>





</dd>
</dl>
    <h2><a name="Fields"></a>Fields</h2>
    <dl class="function">
    <dt>
    <a name = "self.latch_record"></a>
    <strong>self.latch_record</strong>
    </dt>
    <dd>
    (bool) set this to true when data is continuously output







</dd>
    <dt>
    <a name = "self.stop_at_loop"></a>
    <strong>self.stop_at_loop</strong>
    </dt>
    <dd>
    (bool) if true, recording will not cross pattern boundaries







</dd>
    <dt>
    <a name = "self.preferred_playmode"></a>
    <strong>self.preferred_playmode</strong>
    </dt>
    <dd>
    (enum) leave undefined, or set to
 renoise.PatternTrackAutomation.PLAYMODE<em>POINTS
 renoise.PatternTrackAutomation.PLAYMODE</em>LINEAR
 renoise.PatternTrackAutomation.PLAYMODE_CUBIC







</dd>
    <dt>
    <a name = "self.follow_pos"></a>
    <strong>self.follow_pos</strong>
    </dt>
    <dd>
    (enum) how position is determined







</dd>
    <dt>
    <a name = "self.extrapolate_strength"></a>
    <strong>self.extrapolate_strength</strong>
    </dt>
    <dd>
    extrapolation strength, 3 is the default value
 range is from 1 and up, with higher values causing more overshooting
 (when recording, choose point envelopes to avoid extrapolation at all)







</dd>
    <dt>
    <a name = "self._automations"></a>
    <strong>self._automations</strong>
    </dt>
    <dd>
    AutomationLane instances







</dd>
    <dt>
    <a name = "self._skip_updates"></a>
    <strong>self._skip_updates</strong>
    </dt>
    <dd>
    temporarily skip output while recording slider movements







</dd>
    <dt>
    <a name = "self.map"></a>
    <strong>self.map</strong>
    </dt>
    <dd>
    list of active observables







</dd>
    <dt>
    <a name = "self.parameter"></a>
    <strong>self.parameter</strong>
    </dt>
    <dd>
    automation indices are kept here







</dd>
</dl>


</div> <!-- id="content" -->
</div> <!-- id="main" -->
<div id="about">
<i>generated by <a href="http://github.com/stevedonovan/LDoc">LDoc 1.4.2</a></i>
</div> <!-- id="about" -->
</div> <!-- id="container" -->
</body>
</html>
